docs: rewrite README for a public audience, split contributor docs out - #68
Merged
Conversation
The README had drifted from the CLI: it documented ~35 of the 60 commands, still said image building was future work, pointed the default API at localhost:8080, and carried a stale caveat about agents-staging.sh not being on main. It also linked to ../platform, which resolves inside the insta-cloud superproject but 404s on github.com. - Restructure around what a reader needs: install, quickstart, the four concepts (branch-scoped services, the credential seam, approvals, agents), environments, commands, configuration. - Document the npm install path; the package has been published as `insta` since 0.0.1 but the README never mentioned it. - List all 13 command groups and 13 top-level commands at group granularity, and link flags/gates/plan limits to insta-skills/insta/cli-reference.md, which AGENTS.md already designates as the agent-facing surface doc. Keeping one copy of the flag detail is what stops this drifting again. - Fix the staging skill source: it is insta-skills#devel, not @devel. The @ form is parsed as a skill-name filter and silently resolves to main, as env.ts documents. - Move dev loop, architecture, Bun cross-compilation, the release process and local control-plane setup into CONTRIBUTING.md.
Five things in the old README were removed along with the stale staging
caveat they were bundled with. The caveat was out of date; the facts next to
it were not.
- Add an Authentication section: the loopback OAuth flow, `insta login --env`,
and the requirement that a control plane's OAuth app use
{INSTA_API_BASE_URL}/api/auth/callback/<provider> as its callback, not the
CLI's loopback address.
- Restore the explicit staging installer invocation
(`install.sh --agents --staging -y`). agents.staging.instacloud.com is a
CloudFront cache and can serve a stale copy for about a day.
- Restore the installer's hard-fail guarantee when an environment cannot be
applied, now with the version it needs (0.0.23, for `insta env`). Silently
continuing would leave an unattended `curl … | sh && insta project create`
provisioning production.
- Restore the concrete local end-to-end recipe in CONTRIBUTING.md: the docker
Postgres line, `dev:fake`, PORT=8899, and the fact that the signup
verification code goes to the server log in dev mode.
- Keep the codebase's term "secret seam" in the credentials heading.
CarmenDou
marked this pull request as ready for review
July 30, 2026 20:48
jwfing
reviewed
Jul 30, 2026
jwfing
left a comment
jwfing
left a comment
Member
There was a problem hiding this comment.
Review: docs — README rewrite + split out CONTRIBUTING.md
Summary: A docs-only rewrite of README.md for an external audience plus a new CONTRIBUTING.md; I verified essentially every factual claim against the source of truth and it all holds up.
Requirements context
No matching spec/plan found — this repo has no docs/superpowers/ (and no docs/ directory at all), so I assessed against the PR description and the actual sources it claims to have been verified against: src/index.ts, src/env.ts, src/config.ts, src/commands/auth.ts, install.sh, .github/workflows/release.yml, package.json, and LICENSE.
Findings
Critical
(none)
Suggestion
- Functionality / cross-repo link dependency —
README.mdandCONTRIBUTING.mdpoint the reader atinsta/cli-reference.mdoninsta-skills@mainas the flag-level reference. The PR body notes a companioninsta-skillsPR "follows". Since the README now delegates flag/approval/plan-limit accuracy to that file, the linkedmaincopy should already be current (or the companion PR merged first) so a reader following the link on merge day doesn't hit a stale reference. Prod's skill source ismain, so the link target itself is correct — this is a sequencing note, not a defect.
Information
- Software engineering (test coverage) — Docs-only change; no runtime surface, so no new tests are warranted. PR states
npm run typecheckclean andnpm test161 passing; the repo gates areci(typecheck + vitest), consistent withCONTRIBUTING.md. - Functionality (verification notes) — Spot-checked the specific corrections claimed in the PR body and all are accurate:
- Command surface matches
src/index.ts:55-228at group granularity —setup agent,mcp install,run,regions, the 7computesubcommands (start/stop/suspend/status/set-domain/check-domain/remove-domain), the 4observesubcommands,branch merge,services rename/set-access/secrets, andsecrets set/unset/treeare all present. - Default env:
DEFAULT_ENV = 'prod'→https://api.instacloud.com(src/env.ts:30-43) — the oldlocalhost:8080default is correctly gone. - Staging skill ref is
InsForge/insta-skills#devel(src/env.ts:39), and the@-form pitfall is documented inenv.ts:22-26— the fix is real. install.sh: installs to~/.insta/bin, verifiesSHA256SUMS, honoursINSTA_VERSION/INSTA_INSTALL_DIR, and hard-fails (exit 1, "still pointed at PRODUCTION",>= 0.0.23) atinstall.sh:206-218— matches the README's claim exactly.- All nine documented env vars exist in source (
INSTA_API_URL,INSTA_ENV,INSTA_MCP_URL,INSTA_SKILLS_REPO,INSTA_PROJECT_ID,INSTA_ORG_ID,INSTA_BRANCH,INSTA_PASSWORD,INSTA_NO_AUTOUPDATE). release.ymlbuilds five platform binaries +SHA256SUMSand publishes to npm via OIDC trusted publishing with--provenance— matchesCONTRIBUTING.md.- LICENSE is Apache-2.0; npm package name is
insta;.claude/skills/developing-insta-cli/SKILL.mdreferenced byCONTRIBUTING.mdexists.
- Command surface matches
- Security — No security-relevant changes. Worth noting the OAuth self-hosting instructions are correct and safety-relevant: the loopback listener binds
127.0.0.1and the browser opens{apiUrl}/auth/cli/authorize(src/commands/auth.ts:67-71), and the README correctly directs the provider callback to the control plane ({INSTA_API_BASE_URL}/api/auth/callback/<provider>), not the loopback address. - Performance — N/A (documentation).
- Minor —
release.yml:69-72computesSHA256SUMSover the raw binary names then gzips the linux/darwin assets, so the actual release download isinsta-linux-x64.gzetc. (install.shgunzips transparently).CONTRIBUTING.md's "artifacts are namedinsta-linux-x64… and are real native executables" describes the logical/checksum names, which is fine — flagging only for completeness.
Verdict
approved (informational; a human still gives the GitHub approval). Zero Critical findings — this is a careful, well-verified docs rewrite that brings the README back in line with the current CLI. The one Suggestion is a merge-sequencing note on the companion insta-skills PR, not a blocker.
Two things a line-by-line pass against the old README turned up. The old tech-stack line said Node 20; package.json asks for >=18, so CONTRIBUTING now states the version the package actually requires.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="CONTRIBUTING.md">
<violation number="1" location="CONTRIBUTING.md:23">
P3: The statement 'Every command wraps one control-plane API call' is not accurate for `insta upgrade`, which fetches from GitHub/npm registries and does not call the control-plane API.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| ## Architecture | ||
|
|
||
| Node 18 or newer, TypeScript compiled to ESM, [commander](https://github.com/tj/commander.js) | ||
| for the command surface. Every command wraps one control-plane API call. |
There was a problem hiding this comment.
P3: The statement 'Every command wraps one control-plane API call' is not accurate for insta upgrade, which fetches from GitHub/npm registries and does not call the control-plane API.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At CONTRIBUTING.md, line 23:
<comment>The statement 'Every command wraps one control-plane API call' is not accurate for `insta upgrade`, which fetches from GitHub/npm registries and does not call the control-plane API.</comment>
<file context>
@@ -19,6 +19,9 @@ Run `npm run typecheck && npm test` before every commit.
## Architecture
+Node 18 or newer, TypeScript compiled to ESM, [commander](https://github.com/tj/commander.js)
+for the command surface. Every command wraps one control-plane API call.
+
| Path | Responsibility |
</file context>
The command name is already carried by the line under it and by every code block; the heading is better spent matching what GitHub shows above it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
insta-cliis public, and its README had drifted well behind the CLI. This rewrites it for an outside reader and moves contributor material into a newCONTRIBUTING.md.What was wrong
Verified against
src/index.ts,src/env.ts,install.shand the npm registry:setup agent,mcp install,run,regions, all sevencomputesubcommands, all fourobservesubcommands,upgrade/autoupdate,branch merge,services rename/set-access/secrets,secrets set/unset/treehttp://localhost:8080;DEFAULT_ENVisprod→https://api.instacloud.cominsta-skills@devel; the code uses#devel, andenv.tsdocuments that the@form is parsed as a skill-name filter and silently resolves tomainagents-staging.shlands onmain. It is onmaindeploy [dir]with remote Fly builds shippedinstawas never mentioned[platform](../platform)resolves inside the insta-cloud superproject but 404s on github.com, andinsta-platformis privateApproach to the command list
AGENTS.mdalready designatesinsta/cli-reference.mdinInsForge/insta-skillsas the agent-facing surface doc that command and flag changes must be mirrored into. The README was maintaining a second, worse copy of the same table — which is how it drifted.So the README now lists all 13 command groups and 13 top-level commands at group granularity (the whole surface is visible, nothing hidden) and links to
cli-reference.mdfor flags, approval gates and plan limits. Command names change rarely; flags are what drifted.Structure
Rewrote around what a reader needs in order: install → quickstart → the four concepts that make the CLI make sense (branch-scoped services, the credential seam, approvals, the agent surface) → environments → commands → configuration. Dropped the patched-in blockquotes, the inline comment stacks inside copy-paste code blocks, and the four separate passes over "prod and staging are different deployments".
New
CONTRIBUTING.mdtakes the dev loop,src/architecture, the cli-reference mirroring rule, PR conventions, Bun cross-compilation, the release process, and pointing the CLI at a local control plane.Checks
npm run typecheckclean;npm test161 passing across 20 files. Docs-only change.Companion PR for
insta-skillsfollows.Summary by cubic
Rewrite the README for a public audience and align it with the current CLI; move contributor docs into
CONTRIBUTING.md. Clarifies install/auth, environments, and the full command surface; fixes staging details, updates the tech stack, and retitles the README to match the repo.CONTRIBUTING.md; add tech stack (Node ≥18, TypeScript ESM,commander) and build/release steps.npmpaths, agent one‑liner; explicit staging installer (install.sh --agents --staging -y) with CloudFront cache note; auto‑update behavior andinsta autoupdatetoggle.insta login --env; control‑plane callback requirement{INSTA_API_BASE_URL}/api/auth/callback/<provider>; token storage/refresh.InsForge/insta-skills#devel; hard‑fail when environment can’t be applied (<0.0.23).insta/cli-reference.md; document thatinsta statusshows environment, login, and linked project/branch.Written for commit 48c0fae. Summary will update on new commits.